﻿<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
	<title xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory">Appendix F. Event Representation: Object-Array (Object[]) Events</title>
	<link rel="stylesheet" href="css/espertech.css" type="text/css">
	<meta xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" name="generator" content="DocBook XSL-NS Stylesheets V1.74.0">
	<meta xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" http-equiv="Content-Type" content="text/html; charset=UTF-8">
	<link rel="home" href="index.html" title="Esper Reference">
	<link rel="up" href="index.html" title="Esper Reference">
	<link rel="prev" href="appendix_eventrepmap.html" title="Appendix E. Event Representation: java.util.Map Events">
	<link rel="next" href="appendix_eventrepjson.html" title="Appendix G. Event Representation: JSON Events">
</head>

<body>
	<p xmlns:d="http://docbook.org/ns/docbook" id="title"><a href="./index.html" class="site_href"><strong>www.espertech.com</strong></a><a href="http://www.espertech.com/esper/esper-documentation/" class="doc_href"><strong>Documentation</strong></a></p>
	<ul xmlns:d="http://docbook.org/ns/docbook" class="docnav">
		<li class="previous"><a accesskey="p" href="appendix_eventrepmap.html"><strong>Prev</strong></a></li>
		<li class="next"><a accesskey="n" href="appendix_eventrepjson.html"><strong>Next</strong></a></li>
	</ul>
	<div class="appendix" lang="en-US">
		<div class="titlepage">
			<div>
				<div>
					<h2 class="title"><a id="appendix_eventrepoa"></a>Appendix F. Event Representation: Object-Array (<code class="literal">Object[]</code>) Events</h2>
				</div>
			</div>
		</div><a id="d0e61142" class="indexterm"></a><a id="d0e61145" class="indexterm"></a>
		<p>
			This section provides information for using Object-array (<code class="literal">Object[]</code>) to represent events.
		</p>
		<div class="sect1" lang="en-US">
			<div class="titlepage">
				<div>
					<div>
						<h2 class="title"><a id="appendix_eventrepoa_overview"></a>F.1. Overview</h2>
					</div>
				</div>
			</div>
			<p>
				An event can also be represented by an array of objects. Event properties of <code class="literal">Object[]</code> events are the array element values.
			</p>
			<p>
				Similar to the Map event type, the object-array event type takes part in the comprehensive type system that can eliminate the need to use Java classes as event types.
			</p>
			<p>
				A given Object-array event type can have only a single supertype that must also be an Object-array event type. All properties available on the Object-array supertype is also available on the type itself. In addition, anywhere within EPL that an event type name of an Object-array supertype is used, any of its Object-array subtypes and their subtypes match that expression.
			</p>
			<p>
				After your application configures an Object-array event type by providing a type name, the type name can be used when defining further Object-array or Map event types by specifying the type name as a property type or an array property type.
			</p>
			<p>
				One-to-Many relationships in Object-array event types are represented via arrays. A property in an Object-array event type may be an array of primitive, an array of Java object, an array of Map or an array of Object-array.
			</p>
			<p>
				The runtime can process <code class="literal">Object[]</code> events via the <code class="literal">sendEventObjectArray(Object[] array, String eventTypeName)</code> method on the <code class="literal">EPEventService</code> interface. Entries in the Object array represent event properties.
			</p>
			<p>
				The runtime does not validate Object array length or value types. Your application must ensure that Object array values match the declaration of the event type: The type and position of property values must match property names and types in the same exact order and object array length must match the number of properties declared via <code class="literal">create schema</code> or configuration.
			</p>
		</div>
		<div class="sect1" lang="en-US">
			<div class="titlepage">
				<div>
					<div>
						<h2 class="title"><a id="appendix_eventrepoa_properties"></a>F.2. Object-Array Properties</h2>
					</div>
				</div>
			</div>
			<p>
				Object-array event properties can be of any type. Object-array event properties that are Java application objects or that are of type <code class="literal">java.util.Map</code> (or arrays thereof) or that are of type <code class="literal">Object-array</code> (or arrays thereof) offer additional power:
			</p>
			<div class="itemizedlist">
				<ul compact="compact">
					<li>
						<p>
							Properties that are Java application objects can be queried via the nested, indexed, mapped and dynamic property syntax as outlined earlier.
						</p>
					</li>
					<li>
						<p>
							Properties that are of type <code class="literal">Object[]</code> allow object-arrays to be nested arbitrarily deep and thus can be used to represent complex domain information. The nested, indexed, mapped and dynamic property syntax can be used to query object-array within object-arrays and arrays of object-arrays within object-arrays.
						</p>
					</li>
					<li>
						<p>
							Properties that are of type <code class="literal">Map</code> allow Maps to be nested in object-array events and arbitrarily deep. The nested, indexed, mapped and dynamic property syntax can be used to query nested Maps and object-arrays alike.
						</p>
					</li>
				</ul>
			</div>
			<p>
				In order to use <code class="literal">Object[]</code> (object-array) events, the event type name and property names and types, in a well-defined order that must match object-array event properties, must be made known to the compiler via configuration or <code class="literal">create schema</code> EPL syntax. Please see examples in <a class="xref" href="epl_clauses.html#epl_createschema" title="5.15. Declaring an Event Type: Create Schema">Section 5.15, “Declaring an Event Type: Create Schema”</a> and <a class="xref" href="configuration.html#configuration-common-eventtypeobjectarray" title="17.4.5. Events Represented by Object[] (Object-array)">Section 17.4.5, “Events Represented by Object[] (Object-array)”</a>.
			</p>
			<p>
				The code snippet below defines an Object-array event type, creates an Object-array event and sends the event into the runtime. The sample defines the <code class="literal">CarLocUpdateEvent</code> event type via configuration (<code class="literal">create schema</code> could have been used instead).
			</p>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">// Define CarLocUpdateEvent event type (example for configuration API)
String[] propertyNames = {"carId", "direction"};   // order is important
Object[] propertyTypes = {String.class, int.class};  // type order matches name order

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("CarLocUpdateEvent", propertyNames, propertyTypes);</pre>
			<p>
				The <code class="literal">CarLocUpdateEvent</code> can now be used in a statement:
			</p>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">select carId from CarLocUpdateEvent(direction = 1)#time(1 min)</pre>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">// Send an event
Object[] event = {carId, direction};
runtime.getEventService().sendEventObjectArray(event, "CarLocUpdateEvent");</pre>
			<p>
				The runtime can also query Java objects as values in an <code class="literal">Object[]</code> event via the nested property syntax. Thus <code class="literal">Object[]</code> events can be used to
				aggregate multiple data structures into a single event and query the composite information in a convenient way. The example below demonstrates a <code class="literal">Object[]</code> event with a transaction and an account object.
			</p>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">runtime.getEventService().sendEventObjectArray(new Object[] {txn, account}, "TxnEvent");</pre>
			<p>
				An example statement could look as follows:
			</p>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">select account.id, account.rate * txn.amount 
from TxnEvent#time(60 sec) 
group by account.id</pre>
		</div>
		<div class="sect1" lang="en-US">
			<div class="titlepage">
				<div>
					<div>
						<h2 class="title"><a id="appendix_eventrepoa_supertype"></a>F.3. Object-Array Supertype</h2>
					</div>
				</div>
			</div>
			<p>
				Your <code class="literal">Object[]</code> (object-array) event type may declare one supertype when configuring the type.
			</p>
			<p>
				The supertype of a <code class="literal">Object[]</code> event type must also be an object-array event type. All property names and types of a supertype are also available on a subtype and override such same-name properties of the subtype. In addition, anywhere within EPL that an event type name of an Object-array supertype is used, any of its Object-array subtypes also matches that expression (similar to the concept of interface or superclass).
			</p>
			<p>
				The properties provided by the top-most supertype must occur first in the object array. Subtypes each append to the object array. The number of values appended must match the
				number of properties declared by the subtype.
			</p>
			<p>
				For example, assume your application declares the following two types:
			</p>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">create objectarray schema SuperType (p0 string)</pre>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">create objectarray schema SubType (p1 string) inherits SuperType</pre>
			<p>
				The object array event objects that your application can send into the runtime are shown by the next code snippet:
			</p>
			<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">runtime.getEventService().sendEventObjectArray(new Object[] {"p0_value", "p1_value"}, "SubType");
runtime.getEventService().sendEventObjectArray(new Object[] {"p0_value"}, "SuperType");</pre>
		</div>
		<div class="sect1" lang="en-US">
			<div class="titlepage">
				<div>
					<div>
						<h2 class="title"><a id="appendix_eventrepoa_advanced"></a>F.4. Advanced Object-Array Property Types</h2>
					</div>
				</div>
			</div>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="appendix_eventrepoa_arraynested"></a>F.4.1. Nested Properties</h3>
						</div>
					</div>
				</div>
				<p>
					Strongly-typed nested <code class="literal">Object[]</code>-within-<code class="literal">Object[]</code> events can be used to build rich, type-safe event types on the fly. Use the <code class="literal">addEventType</code> method on <code class="literal">Configuration</code> or the <code class="literal">create schema</code> EPL syntax.
				</p>
				<p>
					Noteworthy points are:
				</p>
				<div class="itemizedlist">
					<ul compact="compact">
						<li>
							<p>
								JavaBean (POJO) objects can appear as properties in <code class="literal">Object[]</code> event types.
							</p>
						</li>
						<li>
							<p>
								One may represent Object-array within Object-array and Object-Array-Array within Object-array (same for Map event types) using the name of a previously registered Object-array (or Map) event type.
							</p>
						</li>
						<li>
							<p>
								There is no limit to the number of nesting levels.
							</p>
						</li>
						<li>
							<p>
								Dynamic properties can be used to query <code class="literal">Object[]</code>-within-<code class="literal">Object[]</code> values that may not be known in advance.
							</p>
						</li>
						<li>
							<p>
								The runtime returns a <code class="literal">null</code> value for properties for which the access path into the nested structure cannot be followed where entries do not exist.
							</p>
						</li>
					</ul>
				</div>
				<p>
					For demonstration, in this example our top-level event type is an <code class="literal">AccountUpdate</code> event, which has an <code class="literal">UpdatedFieldType</code> structure as a property. Inside the <code class="literal">UpdatedFieldType</code> structure the example defines various fields, as well as a property by name 'history' that holds a JavaBean class <code class="literal">UpdateHistory</code> to represent the update history for the account. The code snippet to define the event type is thus:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">String[] propertyNamesUpdField = {"name", "addressLine1", "history"};
Object[] propertyTypesUpdField = {String.class, String.class, UpdateHistory.class};

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("UpdatedFieldType", propertyNamesUpdField, propertyTypesUpdField);

String[] propertyNamesAccountUpdate = {"accountId", "fields"};
Object[] propertyTypesAccountUpdate = {long.class, "UpdatedFieldType"};
configuration.getCommon().addEventType("AccountUpdate", propertyNamesAccountUpdate, propertyTypesAccountUpdate);</pre>
				<p>
					The next code snippet populates a sample event and sends the event into the runtime:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">Object[] updatedField = {"Joe Doe", "40 Popular Street", new UpdateHistory()};
Object[] accountUpdate = {10009901, updatedField};

runtime.getEventService().sendEventObjectArray(accountUpdate, "AccountUpdate");</pre>
				<p>
					Last, a sample statement to interrogate <code class="literal">AccountUpdate</code> events is as follows:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">select accountId, fields.name, fields.addressLine1, fields.history.lastUpdate
from AccountUpdate</pre>
			</div>
			<div class="sect2" lang="en-US">
				<div class="titlepage">
					<div>
						<div>
							<h3 class="title"><a id="appendix_eventrepoa_array"></a>F.4.2. One-to-Many Relationships</h3>
						</div>
					</div>
				</div>
				<p>
					To model repeated properties within an Object-array, you may use arrays as properties in an Object-array. You may use an array of primitive types or an array of JavaBean objects or an array of a previously declared Object-array or Map event type.
				</p>
				<p>
					When using a previously declared Object-array event type as an array property, the literal <code class="literal">[]</code> must be appended after the event type name.
				</p>
				<p>
					This following example defines an Object-array event type by name <code class="literal">Sale</code> to hold array properties of the various types. It assumes a <code class="literal">SalesPerson</code> Java class exists and an Object-array event type by name <code class="literal">OrderItem</code> was declared:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">String[] propertyNames = {"userids", "salesPersons", "items"};
Object[] propertyTypes = {int[].class, SalesPerson[].class, "OrderItem[]");

Configuration configuration = new Configuration();
configuration.getCommon().addEventType("SaleEvent", propertyNames, propertyTypes);</pre>
				<p>
					The three properties that the above example declares are:
				</p>
				<div class="itemizedlist">
					<ul>
						<li>
							<p>
								An integer array of user ids.
							</p>
						</li>
						<li>
							<p>
								An array of <code class="literal">SalesPerson</code> Java objects.
							</p>
						</li>
						<li>
							<p>
								An array of Object-array for order items.
							</p>
						</li>
					</ul>
				</div>
				<p>
					The next statement is a sample statement asking for property values held by arrays:
				</p>
				<pre xmlns="" xmlns:d="http://docbook.org/ns/docbook" xmlns:rf="java:org.jboss.highlight.XhtmlRendererFactory" class="">select userids[0], salesPersons[1].name, 
    items[1], items[1].price.amount from SaleEvent</pre>
			</div>
		</div>
	</div>
	<ul xmlns:d="http://docbook.org/ns/docbook" class="docnav">
		<li class="previous"><a accesskey="p" href="appendix_eventrepmap.html"><strong>Prev</strong>Appendix E. Event Representation: java.util.Map E...</a></li>
		<li class="up"><a accesskey="u" href="#"><strong>Top of page</strong></a></li>
		<li class="home"><a accesskey="h" href="index.html"><strong>Front page</strong></a></li>
		<li class="next"><a accesskey="n" href="appendix_eventrepjson.html"><strong>Next</strong>Appendix G. Event Representation: JSON Events</a></li>
	</ul>
</body>

</html>